Inside Macintosh: QuickDraw GX Programmer's Overview / Part 2 - The QuickDraw GX Programming Cookbook

Chapter 8 - Printing

Printing a Document With Custom Formats

This programming recipe discusses how you can print a document that has custom page-formatting information for every page.

Overview of Recipe Steps

The steps in this recipe show you how to:

1. Determine the page range to print
2. Start printing
3. Print each page
4. Finish printing

You need to follow each step of this recipe when printing a document.

Functions Used in This Recipe

QuickDraw GX functions used in this recipe:

GXGetJobPageRange	"Core Printing Features" QuickDraw GX Printing
GXGetJobError	"Core Printing Features" QuickDraw GX Printing
GXStartJob	"Core Printing Features" QuickDraw GX Printing
GXGetJobFormat	"Core Printing Features" QuickDraw GX Printing
GXPrintPage	"Core Printing Features" QuickDraw GX Printing
GXFinishJob	"Core Printing Features" QuickDraw GX Printing

This recipe gives a brief description of these functions; you can find complete reference information for these functions in the Inside Macintosh suite of books.

Recipe Step Descriptions

In this section, each step is described individually.

1. Determine the page range to print

   The Print dialog box allows the user to specify a page range, which QuickDraw GX stores in the job object that you specified when you displayed the Print dialog box. You can use the GXGetJobPageRange function to determine the page range the user specified:

   long firstPage, lastPage;

   GXGetJobPageRange(gCurrent->documentJob,
                     &firstPage,
                     &lastPage);

   if (lastPage > gCurrent->numPages)
       lastPage = gCurrent->numPages;

   After you call the GXGetJobPageRange function, you should check for errors:

   err = GXGetJobError(gCurrent->documentJob);

   If an error occurred, you should handle it and potentially abort the printing process. If no error occurred, you can proceed with Step 2.

2. Start printing

   Before you start printing, you need to inform QuickDraw GX that you
   are about to print. QuickDraw GX provides the GXStartJob function for
   this purpose:

   long howManyPages;

   howManyPages = lastPage - firstPage + 1;

   GXStartJob(gCurrent->documentJob,
              gCurrent->documentTitle,
              howManyPages);

   Notice that you specify the job object and the title of the document you are printing, and the total number of pages. You should check for errors after calling this function:

   err = GXGetJobError(gCurrent->documentJob);

   If no error occurred, you can proceed with Step 3.

3. Print each page

   QuickDraw GX provides two different mechanisms you can use to print. This recipe assumes you have a picture shape representing the image you want to print for each page. The code iterates through the selected range of pages, calling GXPrintPage for each page. Here is the sample code:

   long pg;
   gxFormat pageFormat;

   for (pg = firstPage; (err == noErr) && (pg <= lastPage); pg++)
   {
       pageFormat = gCurrent->pageFormat[pg - 1];

       if (pageFormat == nil)
           pageFormat = GXGetJobFormat(gCurrent->documentJob, 1);

       GXPrintPage(gCurrent->documentJob, pg,
                   pageFormat,
                   gCurrent->documentPage[pg - 1]);

       err = GXGetJobError(gCurrent->documentJob);
   }

   The GXPrintPage function takes four parameters: a reference to the job object, the page number, a reference to the format object for the page, and a reference to the picture for the page.

   If the page has a custom format, you can simply copy the reference to this format from the pageFormat array of the document information structure. If the page doesn't have a custom format, you use the default format for the job. You obtain a reference to the default format object by calling:

   pageFormat = GXGetJobFormat(gCurrent->documentJob, 1);

   This returns the first page format of the job object, which is always the default format.

   If all the pages print with no errors, you can proceed to Step 4.

4. Finish printing

   After you've printed every page in the selected range of pages, you inform QuickDraw GX that you have finished:

   GXFinishJob(gCurrent->documentJob);

   You should also test for errors after calling this function:

   err = GXGetJobError(gCurrent->documentJob);

Related Recipes

For more information about printing with QuickDraw GX, see these recipes:

• "Managing Printing Information," beginning on page 253, shows how to create and dispose of job objects.
• "Handling Printing Dialog Boxes," beginning on page 257, shows you how to display and respond to the printing dialog boxes.
• "Saving Printing Information," described next, shows how to save a
  job object.

The recipes in Chapter 4, "Using the QuickDraw GX Environment," show you how to initialize QuickDraw GX printing. You should read the recipes in that chapter before using the recipes in this chapter.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help